Document custom options#292
Conversation
Bumps [postcss](https://github.com/postcss/postcss) from 8.5.6 to 8.5.10. - [Release notes](https://github.com/postcss/postcss/releases) - [Changelog](https://github.com/postcss/postcss/blob/main/CHANGELOG.md) - [Commits](postcss/postcss@8.5.6...8.5.10) --- updated-dependencies: - dependency-name: postcss dependency-version: 8.5.10 dependency-type: direct:development ... Signed-off-by: dependabot[bot] <support@github.com>
…eview/postcss-8.5.10' into document-custom-options
There was a problem hiding this comment.
Pull request overview
Updates the project’s published version and aligns related build/documentation metadata, while introducing a Time-related documentation dependency and submodule.
Changes:
- Bump Validation SDK and related dependency versions across Gradle, Maven POM output, and docs.
- Add
time-validationas a dependency and exposetime-validation/time-gradle-plugincoordinates inbuildSrc. - Add a new docs
_timeGit submodule and ignore Junie memory output.
Reviewed changes
Copilot reviewed 14 out of 15 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| version.gradle.kts | Bumps the published Validation SDK version to 2.0.0-SNAPSHOT.415. |
| pom.xml | Updates generated first-level dependency versions and adds io.spine.tools:time-validation. |
| docs/content/docs/validation/01-getting-started/adding-to-build.md | Updates example plugin versions referenced in docs. |
| dependencies.md | Refreshes generated dependency/license report for the new version. |
| buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt | Bumps the pinned Validation artifacts version used by build logic. |
| buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt | Bumps Time version and adds helpers for time-validation and time-gradle-plugin. |
| buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt | Bumps Core JVM compiler “dogfooding” version. |
| buildSrc/src/main/kotlin/io/spine/dependency/build/Dokka.kt | Removes an unused import. |
| buildSrc/build.gradle.kts | Removes outdated Shadow plugin compatibility note. |
| .junie/guidelines.md | Generalizes Junie guidance wording to “Spine family of projects”. |
| .gitmodules | Adds docs/_time submodule pointing to SpineEventEngine/time. |
| .gitignore | Ignores .junie/memory/. |
Comments suppressed due to low confidence (1)
buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt:73
Timenow exposesvalidationandgradlePluginartifact coordinates, but they are not included inmodules. SincemodulesdrivesDependency.artifacts/forceArtifacts(), this makes the dependency metadata incomplete and can lead to these new artifacts not being version-forced whenTimeis used that way. Add the new artifacts tomodules(or document why they are intentionally excluded).
fun validation(version: String): String = "${Spine.toolsGroup}:time-validation:$version"
val validation get() = validation(version)
fun gradlePlugin(version: String): String = "${Spine.toolsGroup}:time-gradle-plugin:$version"
val gradlePlugin get() = gradlePlugin(version)
override val modules: List<String>
get() = listOf(
lib,
javaExtensions,
kotlinExtensions,
testLib
).map {
it.split(":").let { (g, artifact) -> "$g:$artifact" }
}
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
This PR updates the Validation SDK snapshot/version references and restructures the “Custom validation” documentation into a multi-page, step-by-step guide (using Spine Time’s (when) option as the running example), keeping the docs navigation in sync.
Changes:
- Bump Validation SDK snapshot versions and align related build/dependency references (Gradle, Maven, docs preview).
- Replace the single-page “Custom validation” doc with a structured section under
05-custom-validation/and update all inbound links + sidenav. - Add Spine Time as a docs submodule (
docs/_time) and introduce/update internal agent/writer guidance to keep nav in sync.
Reviewed changes
Copilot reviewed 40 out of 43 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| version.gradle.kts | Bumps the published Validation SDK snapshot version. |
| pom.xml | Updates project/dependency versions and adds time-validation dependency. |
| docs/data/docs/validation/2-0-0-snapshot/sidenav.yml | Reworks Custom validation nav into a multi-page subtree. |
| docs/content/docs/validation/_index.md | Updates the top-level docs index link to the new Custom validation path. |
| docs/content/docs/validation/09-developers-guide/key-modules.md | Updates “What’s next” link to the new Custom validation section. |
| docs/content/docs/validation/09-developers-guide/architecture.md | Updates “What’s next” link to the new Custom validation section. |
| docs/content/docs/validation/08-custom-validation/_index.md | Removes the old single-page Custom validation doc. |
| docs/content/docs/validation/05-custom-validation/_index.md | Adds the new Custom validation section overview page. |
| docs/content/docs/validation/05-custom-validation/declare-the-option.md | Adds step-by-step doc page for declaring a custom option in Protobuf. |
| docs/content/docs/validation/05-custom-validation/register-the-option.md | Adds step-by-step doc page for registering extensions + wiring ValidationOption. |
| docs/content/docs/validation/05-custom-validation/declare-event-and-view.md | Adds step-by-step doc page for event + projection state protos. |
| docs/content/docs/validation/05-custom-validation/implement-the-reaction.md | Adds step-by-step doc page for implementing a Reaction. |
| docs/content/docs/validation/05-custom-validation/implement-the-view.md | Adds step-by-step doc page for implementing a View. |
| docs/content/docs/validation/05-custom-validation/implement-the-generator.md | Adds step-by-step doc page for implementing a Generator. |
| docs/content/docs/validation/05-custom-validation/pass-to-compiler.md | Adds doc page describing how to put custom options on the Compiler user classpath. |
| docs/content/docs/validation/05-custom-validation/summary.md | Adds recap/summary page for the new section. |
| docs/content/docs/validation/04-validators/implement-a-validator.md | Updates “What’s next” link to new Custom validation section. |
| docs/content/docs/validation/04-validators/_index.md | Updates Custom validation links to new section path. |
| docs/content/docs/validation/03-built-in-options/_index.md | Updates Custom validation link to new section path. |
| docs/content/docs/validation/02-concepts/options-overview.md | Adjusts link formatting and updates Custom validation link. |
| docs/content/docs/validation/02-concepts/error-messages.md | Updates Custom validation link to new section path. |
| docs/content/docs/validation/02-concepts/_index.md | Adjusts link formatting and updates Custom validation links. |
| docs/content/docs/validation/01-getting-started/generated-code.md | Updates Custom validation link to new section path. |
| docs/content/docs/validation/01-getting-started/adding-to-build.md | Updates referenced plugin versions for Validation + CoreJvm. |
| docs/_preview/package.json | Updates postcss dev dependency version. |
| docs/_preview/package-lock.json | Locks postcss to the updated version and updates metadata. |
| dependencies.md | Regenerates dependency/license report for the new snapshot version. |
| buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt | Bumps pinned Validation dependency version used by the build. |
| buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt | Bumps Spine Time version and adds coordinates helpers for Time validation/plugin artifacts. |
| buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt | Bumps CoreJvm Compiler/plugin versions used by the build. |
| buildSrc/src/main/kotlin/io/spine/dependency/build/Dokka.kt | Removes an unused import. |
| buildSrc/build.gradle.kts | Removes outdated Shadow-plugin compatibility note (Shadow version unchanged here). |
| .junie/guidelines.md | Updates Junie guidelines wording to cover Spine family projects. |
| .gitmodules | Adds docs/_time submodule pointing to Spine Time repository. |
| .gitignore | Ignores .junie/memory/ workspace artifacts. |
| .agents/tasks/extend-custom-validation-docs.md | Adds/records a task spec for expanding Custom validation docs. |
| .agents/tasks/document-passing-custom-validation.md | Adds/records a task spec for documenting classpath passing for custom options. |
| .agents/skills/writer/agents/openai.yaml | Updates writer agent prompt to keep sidenav in sync and avoid historical doc edits. |
| .agents/skills/writer/SKILL.md | Documents the repo convention to keep current sidenav.yml in sync with docs changes. |
Files not reviewed (1)
- docs/_preview/package-lock.json: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Updates the Validation documentation to provide a step-by-step guide for implementing custom validation options (based on Spine Time’s (when) option), while also bumping internal dependency/version pins and adjusting docs navigation to reflect the new structure.
Changes:
- Restructures “Custom validation” docs into a dedicated
05-custom-validation/section with multiple focused pages and updates all inbound links/navigation. - Adds a
docs/_timesubmodule reference and updates related dependency coordinates/versions (Validation, Spine Time, Core JVM plugins). - Refreshes generated artifacts and tooling metadata (dependency report, generated POM, docs preview PostCSS).
Reviewed changes
Copilot reviewed 40 out of 43 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| version.gradle.kts | Bumps the published Validation SDK version. |
| pom.xml | Updates generated dependency list + adds time-validation dependency. |
| docs/data/docs/validation/2-0-0-snapshot/sidenav.yml | Replaces single “Custom validation” page with a nested section and new pages. |
| docs/content/docs/validation/_index.md | Updates main landing-page link to the new custom validation section path. |
| docs/content/docs/validation/09-developers-guide/key-modules.md | Updates “What’s next” link to the new custom validation path. |
| docs/content/docs/validation/09-developers-guide/architecture.md | Updates “What’s next” link to the new custom validation path. |
| docs/content/docs/validation/08-custom-validation/_index.md | Removes the old custom validation page. |
| docs/content/docs/validation/05-custom-validation/_index.md | Adds new custom validation section overview page. |
| docs/content/docs/validation/05-custom-validation/declare-the-option.md | New page: declaring custom options in Protobuf. |
| docs/content/docs/validation/05-custom-validation/register-the-option.md | New page: registering options via OptionsProvider + ValidationOption. |
| docs/content/docs/validation/05-custom-validation/declare-event-and-view.md | New page: event + projection state proto definitions. |
| docs/content/docs/validation/05-custom-validation/implement-the-reaction.md | New page: implementing a Reaction for custom options. |
| docs/content/docs/validation/05-custom-validation/implement-the-view.md | New page: implementing a projection View. |
| docs/content/docs/validation/05-custom-validation/implement-the-generator.md | New page: implementing an OptionGenerator. |
| docs/content/docs/validation/05-custom-validation/pass-to-compiler.md | New page: explaining how to place options on the compiler user classpath. |
| docs/content/docs/validation/05-custom-validation/summary.md | New page: recap of the custom option workflow. |
| docs/content/docs/validation/04-validators/implement-a-validator.md | Updates “What’s next” link to the new custom validation path. |
| docs/content/docs/validation/04-validators/_index.md | Updates custom validation link to the new section path. |
| docs/content/docs/validation/03-built-in-options/_index.md | Updates custom validation link to the new section path. |
| docs/content/docs/validation/02-concepts/options-overview.md | Updates link formatting and custom validation link path. |
| docs/content/docs/validation/02-concepts/error-messages.md | Updates custom validation link path. |
| docs/content/docs/validation/02-concepts/_index.md | Updates link formatting and custom validation link path. |
| docs/content/docs/validation/01-getting-started/generated-code.md | Updates custom validation link path. |
| docs/content/docs/validation/01-getting-started/adding-to-build.md | Updates referenced plugin versions in examples. |
| docs/_preview/package.json | Bumps PostCSS version for docs preview tooling. |
| docs/_preview/package-lock.json | Locks PostCSS bump and updates package metadata. |
| dependencies.md | Regenerates dependency/license report with updated versions and timestamps. |
| buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt | Bumps pinned Validation dependency version constant. |
| buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt | Bumps Spine Time version and adds time-validation/time-gradle-plugin coordinates. |
| buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt | Bumps Core JVM compiler/plugin version constants and updates copyright year. |
| buildSrc/src/main/kotlin/io/spine/dependency/build/Dokka.kt | Removes an unused import. |
| buildSrc/build.gradle.kts | Removes outdated Shadow-plugin compatibility note. |
| .junie/guidelines.md | Updates Junie assistant guidance text. |
| .gitmodules | Adds docs/_time submodule entry. |
| .gitignore | Ignores .junie/memory/. |
| .agents/tasks/extend-custom-validation-docs.md | Adds an agent task spec for extending custom validation docs. |
| .agents/tasks/document-passing-custom-validation.md | Adds an agent task spec for documenting classpath wiring. |
| .agents/skills/writer/agents/openai.yaml | Updates writer agent default prompt to emphasize nav sync and versioning rules. |
| .agents/skills/writer/SKILL.md | Documents the “keep docs navigation in sync” convention. |
Files not reviewed (1)
- docs/_preview/package-lock.json: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| /** | ||
| * The version of the Validation library artifacts. | ||
| */ | ||
| const val version = "2.0.0-SNAPSHOT.413" | ||
| const val version = "2.0.0-SNAPSHOT.414" | ||
|
|
||
| /** |
…cument-custom-options # Conflicts: # .agents/tasks/document-passing-custom-validation.md
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a8230b8bf9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| <groupId>io.spine</groupId> | ||
| <artifactId>spine-time</artifactId> | ||
| <version>2.0.0-SNAPSHOT.235</version> | ||
| <version>2.0.0-SNAPSHOT.236</version> |
There was a problem hiding this comment.
Regenerate POM with current Spine Time artifact versions
The checked-in generated pom.xml now advertises spine-time (and time-validation) as 2.0.0-SNAPSHOT.236, but the build dependency source was bumped to 2.0.0-SNAPSHOT.237 in buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt. This leaves the dependency report out of sync with the build’s actual resolved Time artifacts, which can mislead release/audit tooling and reviewers that rely on pom.xml as the canonical first-level dependency snapshot.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
This PR restructures and expands the Validation documentation around “Custom validation” into a multi-page workflow, and updates build/docs metadata to newer snapshot versions.
Changes:
- Replace the single “Custom validation” page with a new multi-page
05-custom-validation/section and update all internal links/navigation accordingly. - Bump published snapshot versions across Gradle/Maven/docs examples, plus update some dependency pins (e.g.,
postcss). - Add the Spine Time repository as a docs submodule (
docs/_time) and extend local dependency helpers for Time.
Reviewed changes
Copilot reviewed 43 out of 46 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| version.gradle.kts | Bumps Validation publish version to .415. |
| pom.xml | Updates generated POM versions/deps; adds time-validation dependency. |
| docs/data/docs/validation/2-0-0-snapshot/sidenav.yml | Reworks nav: “Custom validation” becomes a multi-page section. |
| docs/content/docs/validation/_index.md | Updates root docs link to new custom validation path. |
| docs/content/docs/validation/09-developers-guide/key-modules.md | Updates link to new custom validation path. |
| docs/content/docs/validation/09-developers-guide/architecture.md | Updates link to new custom validation path. |
| docs/content/docs/validation/08-custom-validation/_index.md | Removes old single-page custom validation doc. |
| docs/content/docs/validation/05-custom-validation/_index.md | Adds new “Overview” page for custom validation section. |
| docs/content/docs/validation/05-custom-validation/declare-the-option.md | Adds step: declaring a custom option in Protobuf. |
| docs/content/docs/validation/05-custom-validation/register-the-option.md | Adds step: registering proto extension + ValidationOption. |
| docs/content/docs/validation/05-custom-validation/declare-event-and-view.md | Adds step: define discovery event and view state. |
| docs/content/docs/validation/05-custom-validation/implement-the-reaction.md | Adds step: implement Reaction for the option. |
| docs/content/docs/validation/05-custom-validation/implement-the-view.md | Adds step: implement View projection. |
| docs/content/docs/validation/05-custom-validation/implement-the-generator.md | Adds step: implement generator and querying pattern. |
| docs/content/docs/validation/05-custom-validation/pass-to-compiler.md | Adds step: place option implementation on compiler classpath. |
| docs/content/docs/validation/05-custom-validation/summary.md | Adds recap page for the workflow. |
| docs/content/docs/validation/04-validators/implement-a-validator.md | Updates “What’s next” link to new custom validation path. |
| docs/content/docs/validation/04-validators/_index.md | Updates references to new custom validation path. |
| docs/content/docs/validation/03-built-in-options/_index.md | Updates “What’s next” link to new custom validation path. |
| docs/content/docs/validation/02-concepts/options-overview.md | Minor wording/formatting + updates custom validation link. |
| docs/content/docs/validation/02-concepts/error-messages.md | Updates custom validation link. |
| docs/content/docs/validation/02-concepts/_index.md | Minor wording/formatting + updates custom validation link. |
| docs/content/docs/validation/01-getting-started/generated-code.md | Updates custom validation link. |
| docs/content/docs/validation/01-getting-started/adding-to-build.md | Updates plugin version examples (validation / core-jvm). |
| docs/_preview/package.json | Bumps postcss dev dependency. |
| docs/_preview/package-lock.json | Lockfile update for postcss. |
| dependencies.md | Regenerates dependency/license report for .415. |
| buildSrc/src/main/kotlin/io/spine/dependency/local/Validation.kt | Bumps local Validation dependency version constant. |
| buildSrc/src/main/kotlin/io/spine/dependency/local/Time.kt | Bumps Time version; adds time-validation and Time Gradle plugin aliases. |
| buildSrc/src/main/kotlin/io/spine/dependency/local/CoreJvmCompiler.kt | Bumps CoreJvm compiler plugin versions. |
| buildSrc/src/main/kotlin/io/spine/dependency/build/Dokka.kt | Removes an unused import. |
| buildSrc/build.gradle.kts | Removes outdated Shadow plugin compatibility comment. |
| .junie/guidelines.md | Updates Junie guidelines wording. |
| .gitmodules | Adds docs/_time submodule pointing to Spine Time repo. |
| .gitignore | Ignores .junie/memory/. |
| .agents/skills/writer/agents/openai.yaml | Updates writer agent prompt (nav sync + footnote-link preference). |
| .agents/skills/writer/SKILL.md | Expands writer skill guidance (nav sync + link style). |
Files not reviewed (1)
- docs/_preview/package-lock.json: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * The version of the Validation library artifacts. | ||
| */ | ||
| const val version = "2.0.0-SNAPSHOT.413" | ||
| const val version = "2.0.0-SNAPSHOT.414" |
| <groupId>io.spine</groupId> | ||
| <artifactId>spine-validation-jvm-runtime</artifactId> | ||
| <version>2.0.0-SNAPSHOT.411</version> | ||
| <version>2.0.0-SNAPSHOT.414</version> | ||
| <scope>compile</scope> |
| <dependency> | ||
| <groupId>io.spine.tools</groupId> | ||
| <artifactId>validation-java-bundle</artifactId> | ||
| <version>2.0.0-SNAPSHOT.411</version> | ||
| <version>2.0.0-SNAPSHOT.414</version> | ||
| </dependency> |
| Both `OptionsProvider` and `ValidationOption` are discovered via Java `ServiceLoader`, so the | ||
| `@AutoService` annotation must be present and the annotation processor must run during | ||
| compilation. |
armiol
left a comment
There was a problem hiding this comment.
@alexander-yevsyukov LGTM in general. Please see one comment and one suggestion.
| } | ||
| ``` | ||
|
|
||
| The `id` field must be the **first** field and must be the same type that the `View` uses as its |
There was a problem hiding this comment.
Which "first"? Have the index == 1?
| headline: Documentation | ||
| --- | ||
|
|
||
| # Implement the `Generator` |
There was a problem hiding this comment.
In this section it would be good to have the code for the class. Perhaps, write it step-by-step, and print it at the end with a summary of some sort.
This PR extends the documentation with detailed text in the "Custom validation" section.
Other notable changes
writerskill was improved to update the navigation bar when content changes and use footnote-like links in Markdown.